Guía maestra: Integración de APIs del Servicio de Registro Civil e Identificación (SRCeI) — Chile

Resumen ejecutivo

El SRCeI no expone una API pública abierta. El acceso para organismos públicos y, en algunos casos, entidades privadas con respaldo normativo, se gestiona mediante convenios y la Red/Plataforma de Interoperabilidad del Estado (catálogo PISEE). Los endpoints, esquemas (SOAP/REST) y credenciales se entregan caso a caso tras la aprobación del convenio.

Mapa de acceso & ambientes

• Canal de integración: Red/Plataforma de Interoperabilidad (PISEE). Catálogo, onboarding y llaves se gestionan allí.
• Ambientes: certificación y producción; los hosts/URLs se informan en el expediente de integración.
• Seguridad de transporte: mutual TLS (mTLS), listas blancas de IP y control de red.
• Seguridad de mensaje: WS-Security (firma X.509) para SOAP; para REST, encabezados firmados o mTLS + token según diseño del servicio.
• Autenticación al front (si expones trámites a personas): integrar ClaveÚnica como IdP del Estado.

Requisitos previos

1. Convenio y fundamento legal: resolución/convenio que habilite el intercambio de datos y defina finalidad, trazabilidad y salvaguardas.
2. Alta en PISEE: registro del consumidor, suscripción al servicio, IPs autorizadas, certificados cliente/servidor.
3. Certificados:
   • Certificado cliente (para mTLS).
   • Par de claves y certificado X.509 para firmar mensajes SOAP (WS-Security) cuando aplique.
4. Infra: PHP 8.x con curl, openssl, soap; librería robrichards/xmlseclibs para firmas XML.
5. Privacidad: políticas y controles conforme a la normativa de protección de datos; trazabilidad, minimización y control de acceso.

Arquitectura recomendada (alto nivel)

1. Conector PISEE: módulo HTTP con mTLS, reintentos con backoff y validación de certificados (CA oficial).
2. Cliente SOAP WS-Security: firma y, si corresponde, cifrado de partes del sobre SOAP; verificación de reloj (±5 min).
3. Cliente REST: si el servicio es REST, usar mTLS + token/encabezados firmados provistos por el catálogo.
4. Orquestación: colas de trabajo para desacoplar solicitudes en horas pico; límites por segundo según acuerdo.
5. Auditoría: almacenar huellas (hash) de requests/responses, metadatos, y motivos de consulta (finalidad) por normativa.

Esquema MySQL base

-- Tokens y llaves (si el servicio usa token además de mTLS)
CREATE TABLE rc_tokens (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  scope VARCHAR(40) NOT NULL,           -- p.ej. 'IDENTIDAD', 'VIGENCIA_DOC'
  token VARCHAR(1000) NOT NULL,
  issued_at DATETIME NOT NULL,
  expires_at DATETIME,
  meta JSON,
  UNIQUE KEY uq_scope(scope)
);

-- Registro de consumos (auditoría)
CREATE TABLE rc_consultas (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  servicio VARCHAR(80) NOT NULL,        -- p.ej. 'verificacion_identidad', 'vigencia_cedula'
  finalidad VARCHAR(200) NOT NULL,      -- motivo de la consulta (exigido por convenio)
  run VARCHAR(12),                       -- RUN/RUT consultado (formato 12345678-9)
  serie VARCHAR(20),                     -- serie de cédula si aplica
  request_hash CHAR(64),                 -- SHA-256 del payload enviado
  response_hash CHAR(64),                -- SHA-256 del payload recibido
  http_status INT,
  codigo_rc VARCHAR(20),                 -- código de respuesta propio del servicio
  glosa VARCHAR(255),
  created_at DATETIME NOT NULL,
  correlation_id VARCHAR(64)
);

-- Bitácora técnica (para debugging)
CREATE TABLE rc_logs (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  nivel ENUM('INFO','WARN','ERROR') NOT NULL,
  servicio VARCHAR(80),
  detalle MEDIUMTEXT,
  created_at DATETIME NOT NULL
);

Utilitarios PHP (RUN, certificados, cliente mTLS)

<?php
// Variables de entorno recomendadas:
// RC_CLIENT_CERT (PEM), RC_CLIENT_KEY (PEM), RC_CLIENT_KEY_PASS (opcional), RC_CA_BUNDLE
$CLIENT_CERT = getenv('RC_CLIENT_CERT');     // /secure/client.crt
$CLIENT_KEY  = getenv('RC_CLIENT_KEY');      // /secure/client.key
$CLIENT_KEY_PASS = getenv('RC_CLIENT_KEY_PASS') ?: null;
$CA_BUNDLE   = getenv('RC_CA_BUNDLE');       // /secure/ca-bundle.crt

function normaliza_run($run){
  $run = strtoupper(trim($run));
  $run = preg_replace('/[^0-9K]/','',$run);
  return $run;
}

function calcula_dv($numero){ // módulo 11
  $s=1; for($m=0;$numero;$numero=floor($numero/10)) $s=($s+$numero%10*(9-$m++%6))%11;
  return $s?$s-1:'K';
}

function http_mtps_post($url, $headers, $body){
  global $CLIENT_CERT,$CLIENT_KEY,$CLIENT_KEY_PASS,$CA_BUNDLE;
  $ch = curl_init($url);
  curl_setopt_array($ch, [
    CURLOPT_POST            => true,
    CURLOPT_HTTPHEADER      => $headers,
    CURLOPT_POSTFIELDS      => $body,
    CURLOPT_RETURNTRANSFER  => true,
    CURLOPT_HEADER          => false,
    CURLOPT_TIMEOUT         => 60,
    CURLOPT_SSLCERT         => $CLIENT_CERT,
    CURLOPT_SSLKEY          => $CLIENT_KEY,
    CURLOPT_KEYPASSWD       => $CLIENT_KEY_PASS,
    CURLOPT_CAINFO          => $CA_BUNDLE,
    CURLOPT_SSL_VERIFYPEER  => true,
    CURLOPT_SSL_VERIFYHOST  => 2,
  ]);
  $resp = curl_exec($ch);
  $http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  $err  = curl_error($ch);
  curl_close($ch);
  if($resp === false) throw new RuntimeException("cURL error: ".$err);
  return [$http,$resp];
}
?>

Cliente SOAP con WS-Security (firma X.509)

Algunos servicios del SRCeI utilizan SOAP con WS-Security. A continuación un esqueleto para firmar el Body con xmlseclibs (ajusta referencia/canonicalización según WSDL).

<?php
use RobRichards\XMLSecLibs\XMLSecurityDSig;
use RobRichards\XMLSecLibs\XMLSecurityKey;

function soap_firmado_wsse($xmlBody, $certPemPath, $keyPemPath){
  $doc = new DOMDocument('1.0','UTF-8');
  $envelope = '<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'.
                '<s:Header/>'.
                '<s:Body>'.$xmlBody.'</s:Body>'.
              '</s:Envelope>';
  $doc->loadXML($envelope);

  $xpath = new DOMXPath($doc);
  $xpath->registerNamespace('s','http://schemas.xmlsoap.org/soap/envelope/');
  $body = $xpath->query('//s:Body')->item(0);

  $objDSig = new XMLSecurityDSig();
  $objDSig->setCanonicalMethod(XMLSecurityDSig::EXC_C14N);

  $objDSig->addReference(
    $body,
    XMLSecurityDSig::SHA256,
    ['http://www.w3.org/2000/09/xmldsig#enveloped-signature']
  );

  $objKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'private']);
  $objKey->loadKey($keyPemPath, true);

  $objDSig->sign($objKey);
  $objDSig->add509Cert(file_get_contents($certPemPath), true, false, ['subjectName' => true]);

  // Inserta la firma en Header con bloque WS-Security simple
  $header = $xpath->query('//s:Header')->item(0);
  $wsse = $doc->createElementNS('http://schemas.xmlsoap.org/ws/2002/07/secext','wsse:Security');
  $wsse->setAttribute('s:mustUnderstand','1');
  $wsse->appendChild($doc->importNode($objDSig->sigNode,true));
  $header->appendChild($wsse);

  return $doc->saveXML();
}

// Ejemplo de uso (request genérico)
$body = '<ns:VerificarIdentidad xmlns:ns="urn:rc">'.
          '<ns:RUN>12345678</ns:RUN>'.
          '<ns:DV>'.calcula_dv(12345678).'</ns:DV>'.
          '<ns:Finalidad>Onboarding financiero</ns:Finalidad>'.
        '</ns:VerificarIdentidad>';

$xmlSoap = soap_firmado_wsse($body, $CLIENT_CERT, $CLIENT_KEY);
list($http,$resp) = http_mtps_post('https://<host_certificacion_o_prod>/rc/identidad', [
  'Content-Type: text/xml; charset=utf-8',
  'SOAPAction: "VerificarIdentidad"'
], $xmlSoap);

// Procesar $resp según el esquema XSD del servicio
?>

Cliente REST sobre mTLS (si el servicio es REST)

Algunos servicios pueden ofrecer endpoints REST detrás de mTLS (y, eventualmente, token de corta vida). Esqueleto de envío/recepción:

<?php
$payload = [
  'run'       => '12345678-'.calcula_dv(12345678),
  'finalidad' => 'Validación de identidad',
  'metadatos' => ['canal' => 'web', 'origen' => 'mi-app']
];

list($http,$resp) = http_mtps_post('https://<host_certificacion_o_prod>/rc/api/identidad/validar', [
  'Content-Type: application/json'
], json_encode($payload));
if ($http === 200) {
  $data = json_decode($resp,true);
  // $data['resultado'], $data['nombres'], $data['apellidos'], etc. según contrato
}
?>

Servicios típicos y cómo implementarlos

1) Verificación de identidad por RUN

Entrada: RUN/DV, finalidad. Salida: confirmación de identidad y, según perfil, datos básicos (nombre(s), apellidos, fecha de nacimiento, etc.).

1. Normaliza RUN y DV.
2. Construye el request (SOAP/REST) según el contrato de PISEE.
3. Firma (WS-Security) o autentica (mTLS/Token) y envía.
4. Registra auditoría: finalidad, hash de request/response, resultado.

// Pseudocódigo de parseo de respuesta SOAP
$xml = new SimpleXMLElement($resp);
$ok  = (string)$xml->xpath('//Resultado/Codigo')[0] ?? null;  // p.ej. '00'
$nom = (string)$xml->xpath('//Persona/Nombres')[0] ?? '';
$ap1 = (string)$xml->xpath('//Persona/ApellidoPaterno')[0] ?? '';
$ap2 = (string)$xml->xpath('//Persona/ApellidoMaterno')[0] ?? '';

2) Vigencia de documento (cédula/pasaporte)

Entrada: RUN/DV + serie de cédula (o datos de pasaporte) y finalidad. Salida: estado de vigencia.

// Ejemplo REST (estructura referencial)
$payload = ['run' => '12345678-9', 'serie' => 'ABC123456', 'finalidad' => 'Verificar vigencia de cédula'];
list($http,$resp) = http_mtps_post('https://<host>/rc/api/documentos/vigencia', ['Content-Type: application/json'], json_encode($payload));

3) Consultas registrales / certificación

Según el convenio y perfil, se permite validar/consultar datos de hechos vitales y/o certificados (p. ej., existencia de inscripción). El contrato define qué campos retorna y bajo qué causales se autoriza el consumo.

4) Verificación biométrica (huella)

Flujo de captura local segura + envío de características biométricas a un endpoint autorizado para cotejo con registros del SRCeI. Requiere dispositivos y librerías certificadas; la implementación depende totalmente del contrato.

Paso a paso de implementación

Buenas prácticas

• Minimización: solicita sólo los atributos estrictamente necesarios para tu finalidad.
• Trazabilidad: registra finalidad, responsable y correlación de cada consulta.
• Reloj: sincroniza NTP para evitar fallas de WS-Security por desfase temporal.
• Rotación: renueva certificados y tokens con antelación.
• Backoff: maneja reintentos con exponencial + jitter; evita “martillar”.
• Segregación: separa claves privadas del árbol web; usa HSM o al menos permisos estrictos.

Solución de problemas comunes

Notas y alcance

• Los endpoints, esquemas y códigos exactos se consultan en el catálogo PISEE al que tengas acceso. Esta guía entrega el arquetipo técnico (mTLS, WS-Security, auditoría y patrones de cliente) para implementar cualquier servicio del SRCeI que se publique por esa red.
• Si tu sistema atiende a personas usuarias, implementa ClaveÚnica como método de autenticación ciudadana y registra consentimiento/propósitos cuando corresponda.

Fuentes y referencias

• Plataforma/Red de Interoperabilidad (Catálogo PISEE): portal.pisee.cl
• Estrategia de Gobierno Digital 2030 (gobernanza de identidad digital con liderazgo del SRCeI): PDF
• ClaveÚnica — guía técnica de integración: digital.gob.cl
• ChileAtiende — institución SRCeI (cartas de servicios): chileatiende.gob.cl
• Ejemplo de convenio interinstitucional (vigencia de documentos de identidad): Resolución Exenta SII N°105/2021
• Nueva cédula de identidad digital (contexto público): artículo de prensa

Las URLs exactas de servicios, contratos (WSDL/OpenAPI), códigos de respuesta y límites operacionales pueden cambiar; consulta siempre el catálogo vigente y la documentación entregada en tu expediente de integración.